Support Engineering Group : alfresco.mbari.org Installation Notes

This page last changed on Apr 13, 2012 by kgomes.

In order to best meet the needs of the alfresco installation and get all the pieces working correctly, we decided to buy a new, more powerful server and run Alfresco in Windows. Our thinking was that it would better integrate with our Windows domain at MBARI and the nagging installation issues of times past would be better handled on a windows server. We also purchased an official alfresco license and maintenance contract so that we would have support for any sticky issues we may have.

The new machine arrived and Cathy Sewell was nice enough to get it all setup and installed in the DMZ for us. The machine was hardened so that it was ready to be exposed to the outside world and then it was installed in the DMZ. Here are some particulars from Cathy's email:

- name: alfresco.mbari.org
- It is accessible via Remote Desktop and VNC.
- The IP address (should you need to know) is 134.89.2.15
- The *.mbari.org certificate is installed.

One of my first concerns was how to map a network appliance drive so that software running as a service can access that drive. It looks like the Google-found way is to use the UNC filepath. So for example, use \\tornado.shore.mbari.org\alfresco. I will just have to wait and see if the installation will allow for that.

After signing the contract, Alfresco sent an email that detailed instructions on how to get/install the software and that can be found CLT:here.

Here we go!

I VNC'd to the machine under the account DB_Collaboration as I wanted it to install as a service run under that account.
Started up Firefox and went to http://customers.alfresco.com
I logged in using my username (kgomes@mbari.org) and password that was in the email.
I browsed to "Company Home">"Downloads">"2.1 Releases">"2.1.1"
I then clicked on alfresco-enterprise-tomcat-2.1.1.zip to download the zip file.
Went to http://customers.alfresco.com (I was still logged in)
Went to "Company Home">"Downloads">"2.1 Releases">"2.1.1">"License Files"
I went ahead and downloaded all the "*.lic" files, but I think I only need enterprise-network-customer-unlimited.lic"
Logged out of Alfresco.
Since I suspect I will need a JDBC driver for SQLServer, I downloaded the jTDS-1.2.2 driver from the jtds web site (just Google jtds and go to the download section of the top google return).
I closed the Firefox browser.
I extracted the jtds-1.2.2.jar file from the jtds download

I downloaded and installed the JRockit 6 R27.4 JDK Microsoft Windows (x86 - 32 bit) from BEA's web site

After installing JRockit, make sure you set the JAVA_HOME environment variable to point to the installation of JRockit. For example, I went to the desktop, right clicked on the computer, did Properties, then clicked on the Advanced tab, then click on the environment variables button and then created a new system variable named JAVA_HOME and set to c:\bin\Java\jrockit-R27.4.0-jdk1.6.0_02

I ran the installer, changed the "Program Files" to "bin" in the installation directory for both the JDK and the JRE. I also chose to install the JRE as public.
Using Firefox, I downloaded the PHP 5.2.5 Windows Installer from php.net and installed it. Although I installed it, I did not integrate it with a web server as I want Alfresco to take port 80. I probably did not need to install PHP, but I thought I would anyway. (again, I changed install path from "Program Files" to "bin"
I also downloaded and installed OpenOffice and ran it once so I could get through the initial startup
I setup a Alfresco database on the server Solstice and granted the LAGOON\DB_Collaboration account to be the db_owner of the Alfresco database.
I unzipped the alfresco tomcat zip file to an alfresco directory in c:\bin
I then went to the c:\bin\alfresco\tomcat\shared\classes\alfresco\extensions directory for the customization of the server.
1. I edited the custom-repository.properties file
  1. Changed the dir.root and dir.indexes to look like:
    dir.root=//tornado.shore.mbari.org/Alfresco/alf_data dir.indexes=d:/alf_data/lucene-indexes
  2. Commented out the db.* lines for the HSQL Connection (db.driver and db.url)
  3. Uncommented the db.* lines for MSSQL and changed to use the jTDS driver. They should look like:
    db.driver=net.sourceforge.jtds.jdbc.Driver db.url=jdbc:jtds:sqlserver://solstice.shore.mbari.org/Alfresco;domain=SHORE;user=DB_Collaboration;password=XXXXXXXXX
  4. I also added the following section to override the mail server settings
    # Mail server configuration mail.host=mail.mbari.org mail.port=25 mail.username= mail.password=
2. Edited the custom-hibernate-dialect.properties file
  1. Commented out the HSQL Dialect
  2. Uncommented the MSSQL Dialect
I then installed the jtds-1.2.2.jar in the c:\bin\alfresco\tomcat\common\lib so that it will be on the classpath when Alfresco is started
Now this is not necessarily fun, but in order to really get it configured the way we want it, you need to pull the original .war file out, edit some stuff inside and re-create the .war.

This should all be done before starting Alfresco for the first time.
Copy the c:\Alfresco\tomcat\webapps\alfresco.war file to your home directory.
Make a second copy so that you will always the original (I copied to alfresco.war.orig and moved it somewhere else. It is important to move it and have only the alfresco.war file in the directory because when you un-jar it, all the files go right where alfresco.war is.)
From a command line, un-jar the war file using:
```
jar -xvf alfresco.war
```
This unpacks a lot of files and after it completes, move (or delete) the alfresco.war file from the directory. This needs to be done so it does not end up in the new .war file.
I wanted to change the "Company Home" that seems to be everywhere to something that says MBARI.
1. Edited ./WEB-INF/classes/alfresco/messages/webclient.properties and changed company_home from 'Company Home' to 'MBARI'
2. Edited ./WEB-INF/classes/alfresco/messages/webclient_en_US.properties and changed company_home from 'Company Home' to 'MBARI'
3. I edited ./WEB-INF/classes/alfresco/messages/bootstrap-spaces.properties and changed the first two lines to read
```
spaces.company_home.name=MBARI
spaces.company_home.description=The root space for MBARI
```
4. Edited ./WEB-INF/classes/alfresco/messages/bootstrap-spaces_en_US.properties and made the same changes as the previous step
  
  This took a bit to find all these, and to be honest, I am not sure which one actually made the change on the GUI, but I suspect it was the _en_US ones.

When users are imported via LDAP, user spaces get created automatically. In order to put them where I wanted them to go (instead of right in the Company Home), I edited the ./WEB-INF/classes/alfresco/authentication-services-context.xml file. In the file there is a bean with an name of personalHomeFolderProvider. There is a property name 'path' and I added

/${spaces.user_homes.childname}

to the end to try to get them to create the user spaces there instead of in the Company Home. The final bean XML looks like:

    <bean name="personalHomeFolderProvider" class="org.alfresco.repo.security.person.UIDBasedHomeFolderProvider">
        <property name="serviceRegistry">
            <ref bean="ServiceRegistry" />
        </property>
        <property name="path">
           <value>/${spaces.company_home.childname}/${spaces.user_homes.childname}</value>
        </property>
        <property name="storeUrl">
           <value>${spaces.store}</value>
        </property>
        <property name="homeFolderManager">
            <ref bean="homeFolderManager" />
        </property>
        <property name="inheritsPermissionsOnCreate">
            <value>false</value>
        </property>
        <property name="ownerPemissionsToSetOnCreate">
            <set>
                <value>All</value>
            </set>
        </property>
        <property name="userPemissions">
            <set>
                <value>All</value>
            </set>
        </property>
    </bean>

I wanted to change the logo that is used. I attached the replacement logo CLT:here. Copy this to ./images/logo and overwrite the one that is there.

In order to setup SSL for the application (will do that later), edit ./WEB-INF/web.xml and add the following

   <!-- Added this security constraint to allow for SSL protection -->
   <security-constraint>
      <web-resource-collection>
         <web-resource-name>Login Pages</web-resource-name>
         <url-pattern>/*</url-pattern>
      </web-resource-collection>
      <user-data-constraint>
         <transport-guarantee>CONFIDENTIAL</transport-guarantee>
      </user-data-constraint>
   </security-constraint>

right before the ending </web-app> tag at the bottom of the file.

Now in order to change the default behavior so that all content is versioned from the start, I edited the .\WEB-INF\classes\alfresco\model\contentModel.xml and searched for the content type definition block.

      <type name="cm:content">
         <title>Content</title>
         <parent>cm:cmobject</parent>
         <archive>true</archive>
         <properties>
            <property name="cm:content">
               <type>d:content</type>
               <mandatory>false</mandatory>
               <!--- Index content in the background -->
               <index enabled="true">
                  <atomic>true</atomic>
                  <stored>false</stored>
                  <tokenised>true</tokenised>
               </index>
            </property>
         </properties>
      </type>

and added the following block right before the ending </type> tag:

         <mandatory-aspects>
            <aspect>cm:versionable</aspect>
         </mandatory-aspects>

so the final block looks like:

      <type name="cm:content">
         <title>Content</title>
         <parent>cm:cmobject</parent>
         <archive>true</archive>
         <properties>
            <property name="cm:content">
               <type>d:content</type>
               <mandatory>false</mandatory>
               <!--- Index content in the background -->
               <index enabled="true">
                  <atomic>true</atomic>
                  <stored>false</stored>
                  <tokenised>true</tokenised>
               </index>
            </property>
         </properties>
         <mandatory-aspects>
            <aspect>cm:versionable</aspect>
         </mandatory-aspects>
      </type>

Lastly, I wanted to redirect the log files to a separate disk. This is done because in the Windows hardening process, most of the disk space ends up on drive D: where alfresco does not live. The log files quickly fill up the small C: drive. To to this, I edited the .\WEB-INF\classes\log4j.properties and changed the log file appender location to point to a directory that was created on the D: drive called D:/alf_logs.
That takes care of all the changes to the WAR file. We can now put it back into .war form.
While you are in the directory you expanded the war file in, run
1. jar cvfm alfresco.war META-INF\MANIFEST.MF .
You should now have an alfresco.war file in the directory. Move that back to the alfresco install and overwrite the existing one.

Most users like the details view, so I set the default to that by editing c:\bin\alfresco\tomcat\shared\classes\alfresco\extensions\web-client-config-custom.xml and added:

<!-- MBARI Custom: Added this to change the default view to details -->
<config evaluator="string-compare" condition="Views">
      <!-- the views available in the client -->
      <views>
         <!-- default values for the views available in the client -->
         <view-defaults>
            <browse>
               <!-- allowable values: list|details|icons -->
               <view>details</view>
               <page-size>
                  <list>20</list>
                  <details>20</details>
                  <icons>20</icons>
               </page-size>
            </browse>
         </view-defaults>
      </views>
</config>

right before the closing </alfresco-config> tag.

Now in order to use MBARI accounts, NTLM authentication was turned on and then chained with the native Alfresco accounts so that we could have non-MBARI accounts on the Alfresco server.
1. In order to enable NTLM and native Alfresco authentication, I had to edit two files. For simplicity I have just attached them here and they can be downloaded and installed in the extensions directory.
  1. The first file is the CLT:ntlm-authentication-context.xml file. This configures and enables NTLM authentication.
  2. The next file was the CLT:chaining-authentication-context.xml file which enabled Alfresco authentication and chained it together with the NTLM authentication from the previous file.
Then in order to setup CIFS on the server, I edited the file-servers-custom.xml file to look like the attached CLT:file-servers-custom.xml file.

In order to grant certain accounts admin privs, I created a new custom-authority-services-context.xml in the same directory as the ldap-authentication-context.xml file and added

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>
<beans>
    <bean id="authorityService" class="org.alfresco.repo.security.authority.AuthorityServiceImpl">
        <property name="authenticationComponent">
            <ref bean="authenticationComponent" />
        </property>
        <property name="personService">
            <ref bean="personService" />
        </property>
        <property name="nodeService">
            <ref bean="nodeService" />
        </property>
        <property name="authorityDAO">
            <ref bean="authorityDAO" />
        </property>
        <property name="permissionServiceSPI">
            <ref bean="permissionServiceImpl" />
        </property>
        <property name="adminUsers">
            <set>
    			<value>kgomes</value>
    			<value>admin</value>
    			<value>administrator</value>
    		</set>
        </property>
    </bean>
</beans>

In order for Alfresco to handle all port 80 traffic, I changed Tomcat so that it takes port 80 and SSL goes over port 443. So I edited the c:\Alfresco\tomcat\conf\server.xml file and changed the 8080 port to 80 and the 8443 port to 443 (the 443 change is done in two places).

Now I needed to setup the SSL for the web traffic. Cathy Sewell was instrumental in getting this working. She ordered a new certificate specifically for alfresco and put it in the c:\local\cert folder. Here are the instructions for what she did to get the certficate installed.

SSL certificate for server Alfresco - 1/2/08
C:\bin\Java\jrockit-R27.1.0-jre1.6.0_02\bin>keytool -genkey -alias tomcat -keyalg RSA -keystore tomcat.keystore 

What is your first and last name?

  [alfresco.mbari.org]:

What is the name of your organizational unit?

  [IS]:

What is the name of your organization?

  [MBARI]:

What is the name of your City or Locality?

  [Moss Landing]:

What is the name of your State or Province?

  [CD]:  CA

What is the two-letter country code for this unit?

  [US]:

Is CN=alfresco.mbari.org, OU=IS, O=MBARI, L=Moss Landing, ST=CA, C=US correct?

  [no]:  y

Enter key password for <tomcat>

        (RETURN if same as keystore password):

C:\bin\Java\jrockit-R27.4.0-jre1.6.0_02\bin>keytool -certreq -keyalg RSA -alias

tomcat -file certreq.csr -keystore tomcat.keystore

Enter keystore password:

Generated certificate request file, certreq.csr, was submitted to SSL provider.

Certificate provider sent certificate file (alfresco.mbari.org.crt), along with gd_bundle.crt, 
gd_cross_intermediate.crt, and gd_intermediate.crt.  Additionally, I downloaded valicert_class2_root.cer 
from their website.  These files were stored in c:\local\cert.

The following commands were used to add them to the tomcat keystore:

C:\bin\Java\jrockit-R27.4.0-jre1.6.0_02\bin>keytool -import -alias root -keystore tomcat.keystore 
-trustcacerts -file c:\local\cert\valicert_class2_root.cer

Enter keystore password:

Certificate already exists in system-wide CA keystore under alias <valicertclass2ca>

Do you still want to add it to your own keystore? [no]:  y

Certificate was added to keystore

C:\bin\Java\jrockit-R27.4.0-jre1.6.0_02\bin>keytool -import -alias cross -keystore tomcat.keystore 
-trustcacerts -file c:\local\cert\gd_cross_intermediate.crt

Enter keystore password:

Certificate was added to keystore

C:\bin\Java\jrockit-R27.4.0-jre1.6.0_02\bin>keytool -import -alias intermed -keystore tomcat.keystore 
-trustcacerts -file c:\local\cert\gd_intermediate.crt

Enter keystore password:

Certificate was added to keystore

C:\bin\Java\jrockit-R27.4.0-jre1.6.0_02\bin>keytool -import -alias tomcat -keystore tomcat.keystore 
-trustcacerts -file c:\local\cert\alfresco.mbari.org.crt

Enter keystore password:

Certificate reply was installed in keystore

I edited the c:\bin\alfresco\tomcat\conf\server.xml file and uncommented the SSL section and edited to look like that shown below.

    <Connector port="443" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" disableUploadTimeout="true"
               acceptCount="100" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS" 
               keystoreFile="c:/bin/Java/jrockit-R27.4.0-jre1.6.0_02/bin/tomcat.keystore" keystorePass="******"/>

Since I was in the server.xml file, I went ahead and changed it so that the default webapp was alfresco so that you would get alfresco anytime you went to the base URL. I did this by adding:
```
        <Context path="" docBase="alfresco" debug="0" >
          <Valve className="org.apache.catalina.authenticator.FormAuthenticator" disableProxyCaching="false" />
        </Context>
```
as the last line of the <Host> tag section (right before the closing </Host> tag).

You will also notice the Valve tag that I had to add to turn off proxy cache disabling so that IE clients would work correctly over SSL. Gotta love M$.
I copied the enterprise-network-unlimited.lic file into the c:\Alfresco\tomcat\shared\classes\alfresco\extensions\license directory
Just to keep things clean, I edited the c:\bin\alfresco\alfresco.bat file and put 'rem' in front of the second JAVA_OPTS set as I am using Java 6.
Now after you run it for the first time and the database structure gets created, you can't restart it because you get:
```
java.sql.SQLException: Column names in each table must be unique. Column name 'ID_' in table 'JBPM_ACTION' is specified more than once.
```
Sigh, so in order to keep Alfresco from hurting itself, I had to turn off the schema updates. This is done by editing the c:\bin\alfresco\tomcat\shared\classes\alfresco\extensions\custom-repository.properties and adding the following:
```
db.schema.update=false
```
and then restarting alfresco.

To install Alfresco as a Windows Service use a command prompt and enter the following:

cd c:\bin\alfresco\tomcat\bin
service.bat install alfresco
tomcat5.exe //US//alfresco --DisplayName "Alfresco Server"
tomcat5.exe //US//alfresco --JvmMs=512 --JvmMx=1024 --JvmSs=64
tomcat5.exe //US//alfresco --JavaHome=c:/bin/Java/jrockit-R27.4.0-jdk1.6.0_02
tomcat5.exe //US//alfresco --Environment ALF_HOME=c:/bin/alfresco/
tomcat5.exe //US//alfresco --Environment PATH=c:/bin/alfresco/bin;%PATH%
tomcat5.exe //US//alfresco --StartPath c:/bin/alfresco --Startup auto

JRockit Dump Size

As Alfresco was running, we noticed JRockit was occasionally creating these HUGE dump files that would fill up the hard drive. I turned this "feature" off by running tomcat5w.exe and in the popup GUI, I added a Java command line option: -XXdumpSize:none to turn off the dump files.

To uninstall the service, at a later time, do the following:

cd c:\bin\alfresco\tomcat\bin
service.bat uninstall alfresco

To edit your service settings at any time:

cd c:\alfresco\tomcat\bin
tomcat5w.exe //ES//alfresco

These next couple of steps had to be taken to install a patch from Alfresco for an issue with bulk uploads I was having. Essentially when file and path structures get really long and nasty, Alfresco was throwing an error and bailing out. This patch (two Java classes) fixed that issue.

Next, I downloaded the attached CLT:JAR file and copied it to the c:\bin\alfresco\tomcat\webapps\alfresco\WEB-INF\classes directory.
I shutdown Alfresco and then unjarred the file to install the new classes. They are:
1. org/alfresco/filesys/smb/server/SMBSrvPacket.class
2. org/alfresco/filesys/util/DataBuffer.class
I would assume since they do not overwrite anything, that this location is further up in the class loader and so it will load these new classes first.
I deleted the act2139.jar file and the META-INF directory that the unjarring process created.
In order to install certain modules (like the email listener), I had to get the Alfresco Module Manager from the customers.alfresco.com download site. I downloaded the alfresco-mmt-2.1.1.jar file locally so I could use it to install modules.
I then downloaded the email listener module from http://forge.alfresco.com/projects/email-listener/. It came as a zip file, so I unzipped it and it created a folder with the appropriate emailListener.amp in it.
Make another backup copy of the alfresco.war file and put somewhere in case you want to roll this back.
Open a command prompt windows and cd to the location where the Alfresco Module Manager jar is.

Run the following:

java -jar alfresco-mmt-2.1.1.jar path_to_emailListener.amp path_to_alfresco.war

So for me this looked like:

java -jar alfresco-mmt-2.1.1.jar .\email-listener_2.1RC2\emailListener.amp c:\bin\alfresco\tomcat\webapps\alfresco.war

You should be able to verify the install by running:

java -jar alfresco-mmt-2.1.1.jar list c:\bin\alfresco\tomcat\webapps\alfresco.war

and you should see something like:

Module 'emailListener' installed in 'c:\bin\alfresco\tomcat\webapps\alfresco.war'
   -    Title:        EmailListener
   -    Version:      2.1
   -    Install Date: Fri Dec 07 08:43:10 PST 2007
   -    Desription:   EmailListener Module

Finally, to start the service, just go into your Windows Service control panel and locate the service that is now named 'Alfresco Server'. You can start and stop Alfresco from this control panel.

Database Migrations

For the alfresco.mbari.org installation, we moved the back end database a couple of times for performance and management reasons. The first move was to backup the database from solstice.shore.mbari.org to the SQL 2005 server called capricorn. We did this because 2005 was the officially supported DB and we were experiencing some strange issues. It ran fine on capricorn for a long while, but for licensing reasons, we wanted to consolidate the DB onto a newer SQL Server 2008 machine called equinox.shore.mbari.org. In order to point Alfresco at a different database, I edited the custom-repository.properties file located in the

c:\bin\alfresco\tomcat\shared\classes\alfresco\extension

directory. Here is what the final result looked like with the previous two configurations commented out.

#
# SQLServer connection (requires jtds-1.2.jar or equivalent - http://jtds.sourceforge.net/)
#
db.driver=net.sourceforge.jtds.jdbc.Driver
# DB on Solstice
#db.url=jdbc:jtds:sqlserver://solstice.shore.mbari.org/Alfresco;domain=SHORE;user=DB_Collaboration;password=xxxxxx
# DB on capricorn
#db.url=jdbc:jtds:sqlserver://capricorn.shore.mbari.org/Alfresco;domain=SHORE;user=DB_Collaboration;password=xxxxxx
# DB on equinox
db.url=jdbc:jtds:sqlserver://equinox.shore.mbari.org/Alfresco;domain=SHORE;user=DB_Collaboration;password=xxxxxx

I also downloaded the most recent jtds driver (1.2.5) and installed it in the c:\bin\alfresco\tomcat\common\lib directory and removed the old version.

Content Migration

Now, in order to migrate content from old alfresco and normal file structures, I did the following:

For content already in alfresco:

Navigate to the space whose contents you want to migrate. For example, let's say I want to migrate the stuff from my personal space. I would navigate (using the WebUI) to the /MBARI/User Homes/kgomes space. You should see the contents of the kgomes folder from this view.
Click on 'More actions->View Details'.
On the right hand side, click on 'Export'.
For package name, I usually enter the space name followed by '_export', but it doesn't really matter.
Click on the link that says 'Click here to select the destination' and select somewhere that you will be able to download the .acp file from.
Select 'Current Space'.
Select 'Include Children'.
Uncheck 'Include this space' unless you have content (documents) in this specific folder (anything other than folders) that you want to migrate. This is a bit tricky, but there are two ways to do this. If you want to have the top level folder created, use the 'Include this space' and that will create the top level folder. Otherwise, if will expand into the folder in which you import the .acp file into. This is important in cases where the folder has already been created for you (like with user homes) and you have to migrate content into that folder. If you have the option to create the top level directory, by all means do so.
Uncheck 'Export in background' so you can force it to happen and you know when it is complete.

Attachments:

Welcome_to_Alfresco.txt (text/plain)

AlfrescoLogo32.png (image/png)

chaining-authentication-context.xml (text/xml)

ntlm-authentication-context.xml (text/xml)

file-servers-custom.xml (text/xml)

act2139.jar (application/octet-stream)

Document generated by Confluence on Feb 03, 2026 16:22